home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 April: Mac OS SDK / Dev.CD Apr 00 SDK1.toast / Development Kits / Mac OS / AppleShare Client API SDK / Headers / afpClient.h next >
Encoding:
C/C++ Source or Header  |  1999-11-02  |  14.4 KB  |  373 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        afpClient.h
  3.  
  4.      Contains:    Shared library interface to the AppleShare Client.
  5.  
  6.      Version:    3.8.5
  7.  
  8. */
  9. #ifndef __AFPCLIENT__
  10. #define __AFPCLIENT__
  11.  
  12. #ifndef __CODEFRAGMENTS__
  13. #include <CodeFragments.h>
  14. #endif
  15.  
  16. #ifndef __OPENTRANSPORT__
  17. #include <OpenTransport.h>
  18. #endif
  19.  
  20. #ifndef __EVENTS__
  21. #include <Events.h>
  22. #endif
  23.  
  24.  
  25.  
  26.  
  27. #if PRAGMA_ONCE
  28. #pragma once
  29. #endif
  30.  
  31. #ifdef __cplusplus
  32. extern "C" {
  33. #endif
  34.  
  35. #if PRAGMA_IMPORT
  36. #pragma import on
  37. #endif
  38.  
  39. #if PRAGMA_STRUCT_ALIGN
  40.     #pragma options align=mac68k
  41. #elif PRAGMA_STRUCT_PACKPUSH
  42.     #pragma pack(push, 2)
  43. #elif PRAGMA_STRUCT_PACK
  44.     #pragma pack(2)
  45. #endif
  46.  
  47.  
  48. /* Data Types */
  49. typedef UInt32                             AFPSharedVolumesEnumeratorRef;
  50. typedef UInt32                             ATEventCode;
  51. typedef UInt32                             ATPortRef;
  52. typedef UInt32                             OneBasedIndex;
  53.  
  54. /* error codes    */
  55. enum {
  56.     kNavigationAPIErrorBase        = 1,
  57.     kATEnumeratorBadIndexErr    = kNavigationAPIErrorBase,
  58.     kATEnumeratorBadReferenceErr = 2,
  59.     kATEnumeratorBadZoneErr        = 3,
  60.     kATEnumeratorBadPortErr        = 4,
  61.     kATAppleShareNotAvailableErr = 5,
  62.     kATServerNotFoundErr        = 6,
  63.     kLastErrorCodeIndex            = 7,
  64.     kLastAndMeaningLessItemInEnum = 8
  65. };
  66.  
  67.  
  68. /* notifier events for ATNotifyProc    */
  69. enum {
  70.                                                                 /* Returned by the AppleShare volumes emnumerator*/
  71.     AT_SHAREDVOLUMES_COMPLETE    = FOUR_CHAR_CODE('vols')
  72. };
  73.  
  74. /*---------------------------------------------------------------------------*/
  75. /*    Finding out if the library is present and getting its version             */
  76. /*---------------------------------------------------------------------------*/
  77.  
  78. EXTERN_API( UInt32 )
  79. AFPLibraryVersion                (void);
  80.  
  81. EXTERN_API_C( Boolean )
  82. AFPLibraryPresent                (void);
  83.  
  84.  
  85. #ifdef __cplusplus                                                        
  86. inline    Boolean AFPLibraryPresent()                                        
  87. {                                                                        
  88.     return AFPLibraryVersion != (void*)kUnresolvedCFragSymbolAddress;    
  89. }                                                                        
  90. #endif                                                                    
  91.  
  92. /*---------------------------------------------------------------------------*/
  93. /*---------------------------------------------------------------------------*/
  94. /*    AFP URL Support                                                             */
  95. /*---------------------------------------------------------------------------*/
  96.  
  97. /*---------------------------------------------------------------------------*/
  98. /* Building and disposing of an AFP URL                                         */
  99. /*---------------------------------------------------------------------------*/
  100. EXTERN_API_C( char *)
  101. NewAFPURL                        (StringPtr                 protocolName,
  102.                                  StringPtr                 serverNameOrHost,
  103.                                  StringPtr                 zoneNameOrNULL,
  104.                                  StringPtr                 uamName,
  105.                                  StringPtr                 userName,
  106.                                  StringPtr                 password,
  107.                                  StringPtr                 volume,
  108.                                  StringPtr                 path);
  109.  
  110. EXTERN_API_C( void )
  111. DisposeAFPURL                    (char *                    url);
  112.  
  113.  
  114. /*---------------------------------------------------------------------------*/
  115. /* Parsing an AFP URL: IsAFPURL simply tests the scheme                         */
  116. /*---------------------------------------------------------------------------*/
  117. EXTERN_API_C( Boolean )
  118. IsAFPURL                        (char *                    url);
  119.  
  120. /*---------------------------------------------------------------------------*/
  121. /* ParseAFPURL parses all the fields of the URL. Any StringPtr can be NULL,     */
  122. /* If provided the StringPtr must point to a string large enough to          */
  123. /* accomodate maximum length value (Str255)                                     */
  124. /*---------------------------------------------------------------------------*/
  125. EXTERN_API_C( OSStatus )
  126. ParseAFPURL                        (char *                    url,
  127.                                  StringPtr                 protocolName,
  128.                                  StringPtr                 serverNameOrHost,
  129.                                  StringPtr                 zoneNameOr,
  130.                                  StringPtr                 uamName,
  131.                                  StringPtr                 userName,
  132.                                  StringPtr                 password,
  133.                                  StringPtr                 volume,
  134.                                  StringPtr                 path);
  135.  
  136.  
  137.  
  138. /*---------------------------------------------------------------------------*/
  139. /*---------------------------------------------------------------------------*/
  140. /*    Enumerating shared volumes on AppleShare file servers                     */
  141. /*---------------------------------------------------------------------------*/
  142.  
  143. /*---------------------------------------------------------------------------*/
  144. /*    Event callback for the login dialogs                                     */
  145. /*---------------------------------------------------------------------------*/
  146. typedef CALLBACK_API( void , AShareEventProcPtr )(EventRecord *theEvent, void *contextPtr);
  147. typedef CALLBACK_API( void , ATNotifyProcPtr )(void *contextPtr, ATEventCode code, OSStatus result, void *cookie);
  148. typedef CALLBACK_API( Boolean , ATFilterProcPtr )(StringPtr name, void *data);
  149. typedef CALLBACK_API( void , ATNetworkEventNotifierProcPtr )(UInt32 eventCode, void *cookie);
  150. typedef STACK_UPP_TYPE(AShareEventProcPtr)                         AShareEventUPP;
  151. typedef STACK_UPP_TYPE(ATNotifyProcPtr)                         ATNotifyUPP;
  152. typedef STACK_UPP_TYPE(ATFilterProcPtr)                         ATFilterUPP;
  153. typedef STACK_UPP_TYPE(ATNetworkEventNotifierProcPtr)             ATNetworkEventNotifierUPP;
  154.  
  155. #if OPAQUE_UPP_TYPES
  156.     EXTERN_API(AShareEventUPP)
  157.     NewAShareEventUPP               (AShareEventProcPtr        userRoutine);
  158.  
  159.     EXTERN_API(ATNotifyUPP)
  160.     NewATNotifyUPP                   (ATNotifyProcPtr            userRoutine);
  161.  
  162.     EXTERN_API(ATFilterUPP)
  163.     NewATFilterUPP                   (ATFilterProcPtr            userRoutine);
  164.  
  165.     EXTERN_API(ATNetworkEventNotifierUPP)
  166.     NewATNetworkEventNotifierUPP    (ATNetworkEventNotifierProcPtr userRoutine);
  167.  
  168.     EXTERN_API(void)
  169.     DisposeAShareEventUPP           (AShareEventUPP            userUPP);
  170.  
  171.     EXTERN_API(void)
  172.     DisposeATNotifyUPP               (ATNotifyUPP                userUPP);
  173.  
  174.     EXTERN_API(void)
  175.     DisposeATFilterUPP               (ATFilterUPP                userUPP);
  176.  
  177.     EXTERN_API(void)
  178.     DisposeATNetworkEventNotifierUPP    (ATNetworkEventNotifierUPP userUPP);
  179.  
  180.     EXTERN_API(void)
  181.     InvokeAShareEventUPP           (EventRecord *            theEvent,
  182.                                     void *                    contextPtr,
  183.                                     AShareEventUPP            userUPP);
  184.  
  185.     EXTERN_API(void)
  186.     InvokeATNotifyUPP               (void *                    contextPtr,
  187.                                     ATEventCode                code,
  188.                                     OSStatus                result,
  189.                                     void *                    cookie,
  190.                                     ATNotifyUPP                userUPP);
  191.  
  192.     EXTERN_API(Boolean)
  193.     InvokeATFilterUPP               (StringPtr                name,
  194.                                     void *                    data,
  195.                                     ATFilterUPP                userUPP);
  196.  
  197.     EXTERN_API(void)
  198.     InvokeATNetworkEventNotifierUPP    (UInt32                eventCode,
  199.                                     void *                    cookie,
  200.                                     ATNetworkEventNotifierUPP userUPP);
  201.  
  202. #else
  203.     enum { uppAShareEventProcInfo = 0x000003C0 };                     /* pascal no_return_value Func(4_bytes, 4_bytes) */
  204.     enum { uppATNotifyProcInfo = 0x00003FC0 };                         /* pascal no_return_value Func(4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  205.     enum { uppATFilterProcInfo = 0x000003D0 };                         /* pascal 1_byte Func(4_bytes, 4_bytes) */
  206.     enum { uppATNetworkEventNotifierProcInfo = 0x000003C0 };         /* pascal no_return_value Func(4_bytes, 4_bytes) */
  207.     #define NewAShareEventUPP(userRoutine)                             (AShareEventUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppAShareEventProcInfo, GetCurrentArchitecture())
  208.     #define NewATNotifyUPP(userRoutine)                             (ATNotifyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppATNotifyProcInfo, GetCurrentArchitecture())
  209.     #define NewATFilterUPP(userRoutine)                             (ATFilterUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppATFilterProcInfo, GetCurrentArchitecture())
  210.     #define NewATNetworkEventNotifierUPP(userRoutine)                 (ATNetworkEventNotifierUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppATNetworkEventNotifierProcInfo, GetCurrentArchitecture())
  211.     #define DisposeAShareEventUPP(userUPP)                             DisposeRoutineDescriptor(userUPP)
  212.     #define DisposeATNotifyUPP(userUPP)                             DisposeRoutineDescriptor(userUPP)
  213.     #define DisposeATFilterUPP(userUPP)                             DisposeRoutineDescriptor(userUPP)
  214.     #define DisposeATNetworkEventNotifierUPP(userUPP)                 DisposeRoutineDescriptor(userUPP)
  215.     #define InvokeAShareEventUPP(theEvent, contextPtr, userUPP)     CALL_TWO_PARAMETER_UPP((userUPP), uppAShareEventProcInfo, (theEvent), (contextPtr))
  216.     #define InvokeATNotifyUPP(contextPtr, code, result, cookie, userUPP)  CALL_FOUR_PARAMETER_UPP((userUPP), uppATNotifyProcInfo, (contextPtr), (code), (result), (cookie))
  217.     #define InvokeATFilterUPP(name, data, userUPP)                     (Boolean)CALL_TWO_PARAMETER_UPP((userUPP), uppATFilterProcInfo, (name), (data))
  218.     #define InvokeATNetworkEventNotifierUPP(eventCode, cookie, userUPP)  CALL_TWO_PARAMETER_UPP((userUPP), uppATNetworkEventNotifierProcInfo, (eventCode), (cookie))
  219. #endif
  220.  
  221. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  222. #define NewAShareEventProc(userRoutine)                         NewAShareEventUPP(userRoutine)
  223. #define NewATNotifyProc(userRoutine)                             NewATNotifyUPP(userRoutine)
  224. #define NewATFilterProc(userRoutine)                             NewATFilterUPP(userRoutine)
  225. #define NewATNetworkEventNotifierProc(userRoutine)                 NewATNetworkEventNotifierUPP(userRoutine)
  226. #define CallAShareEventProc(userRoutine, theEvent, contextPtr)    InvokeAShareEventUPP(theEvent, contextPtr, userRoutine)
  227. #define CallATNotifyProc(userRoutine, contextPtr, code, result, cookie) InvokeATNotifyUPP(contextPtr, code, result, cookie, userRoutine)
  228. #define CallATFilterProc(userRoutine, name, data)                InvokeATFilterUPP(name, data, userRoutine)
  229. #define CallATNetworkEventNotifierProc(userRoutine, eventCode, cookie) InvokeATNetworkEventNotifierUPP(eventCode, cookie, userRoutine)
  230.  
  231. /*---------------------------------------------------------------------------*/
  232. /* AFPCreateSharedVolumesEnumerator: creates an enumerator for the volumes      */
  233. /* on an AppleShare server.                                                     */
  234. /*                                                                             */
  235. /* Accepts an optional volume name filter to restrict the volumes matched.     */
  236. /* Use the predefined filters or your own or pass NULL to match all volumes     */
  237. /* Accepts an optional notifier to call when the list of volumes has been     */
  238. /* found.                                                                      */
  239. /* Pass NULL for polling mode                                                 */
  240. /* For connections over TCP/IP pass NULL for serverZone and the DNS name in     */
  241. /* serverName.                                                                 */
  242. /* These calls may put up UI, pass a UPP to a routine to handle events that     */
  243. /* affect other windows in your application.                                 */
  244. /*---------------------------------------------------------------------------*/
  245.  
  246. EXTERN_API( OSStatus )
  247. AFPCreateSharedVolumesEnumerator (StringPtr             serverName,
  248.                                  StringPtr                 serverZone,
  249.                                  StringPtr                 uamName,
  250.                                  StringPtr                 userName,
  251.                                  StringPtr                 password,
  252.                                  AShareEventUPP         callback,
  253.                                  void *                    evtContext,
  254.                                  ATFilterUPP             filter,
  255.                                  void *                    filterParam,
  256.                                  ATNotifyUPP             notifier,
  257.                                  void *                    contextPtr,
  258.                                  AFPSharedVolumesEnumeratorRef * ref);
  259.  
  260. /*---------------------------------------------------------------------------*/
  261. /*    AFPGetSharedVolumesCount: returns the number of AppleShare volumes          */
  262. /*  found so far. Indicates if all volumes have been found                     */
  263. /*---------------------------------------------------------------------------*/
  264. EXTERN_API( OSStatus )
  265. AFPGetSharedVolumesCount        (AFPSharedVolumesEnumeratorRef  ref,
  266.                                  Boolean *                allFound,
  267.                                  UInt32 *                count);
  268.  
  269. /*---------------------------------------------------------------------------*/
  270. /*    AFPGetIndexedSharedVolume: returns the name of volumes by index             */
  271. /*---------------------------------------------------------------------------*/
  272. EXTERN_API( OSStatus )
  273. AFPGetIndexedSharedVolume        (AFPSharedVolumesEnumeratorRef  ref,
  274.                                  OneBasedIndex             index,
  275.                                  StringPtr                 volumeName);
  276.  
  277. /*---------------------------------------------------------------------------*/
  278. /*  AFPGetSharedVolumesListPtr: returns a pointer on the list of all volumes */
  279. /*---------------------------------------------------------------------------*/
  280.  
  281. EXTERN_API( OSStatus )
  282. AFPGetSharedVolumesListPtr        (AFPSharedVolumesEnumeratorRef  ref,
  283.                                  StringPtr **            volumesListPtr);
  284.  
  285. /*---------------------------------------------------------------------------*/
  286. /*    AFPSortSharedVolumes: sorts the list of volumes by alphabetical order     */
  287. /*---------------------------------------------------------------------------*/
  288. EXTERN_API( OSStatus )
  289. AFPSortSharedVolumes            (AFPSharedVolumesEnumeratorRef  ref);
  290.  
  291. /*---------------------------------------------------------------------------*/
  292. /*    AFPMountSharedVolume: mounts a volume by name,                              */
  293. /* leave isMounted NULL if you don't care wether or not the volume was         */
  294. /* already mounted                                                             */
  295. /*---------------------------------------------------------------------------*/
  296. EXTERN_API( OSStatus )
  297. AFPMountSharedVolume            (AFPSharedVolumesEnumeratorRef  ref,
  298.                                  Str255                 volumeName,
  299.                                  short *                volumeRefNum,
  300.                                  Boolean *                isMounted);
  301.  
  302.  
  303. /*---------------------------------------------------------------------------*/
  304. /* AFPGetMountAtStartup: returns the startup mounting state of the named      */
  305. /* volume;                                                                   */
  306. /*  returns noErr if the volume is set to mount at startup                     */
  307. /*  returns nsvErr if the volume is not set to mount at startup                 */
  308. /*---------------------------------------------------------------------------*/
  309.  
  310. EXTERN_API( OSStatus )
  311. AFPGetMountAtStartup            (AFPSharedVolumesEnumeratorRef * ref,
  312.                                  StringPtr                 volumeName);
  313.  
  314. /*---------------------------------------------------------------------------*/
  315. /* AFPSetMountAtStartup: sets the startup mounting state of the named volume */
  316. /*---------------------------------------------------------------------------*/
  317.  
  318. EXTERN_API( OSStatus )
  319. AFPSetMountAtStartup            (AFPSharedVolumesEnumeratorRef * ref,
  320.                                  StringPtr                 volumeName,
  321.                                  Boolean                 toMount);
  322.  
  323.  
  324. /*---------------------------------------------------------------------------*/
  325. /* AFPDeleteSharedVolumesEnumerator: deletes the enumerator                     */
  326. /*---------------------------------------------------------------------------*/
  327.  
  328. EXTERN_API( OSStatus )
  329. AFPDeleteSharedVolumesEnumerator (AFPSharedVolumesEnumeratorRef * ref);
  330.  
  331. /*---------------------------------------------------------------------------*/
  332. /* AFPGetLoginInformation: returns the login information (will change)         */
  333. /*---------------------------------------------------------------------------*/
  334.  
  335. EXTERN_API( OSStatus )
  336. AFPGetLoginInformation            (AFPSharedVolumesEnumeratorRef  ref,
  337.                                  Boolean *                isGuest,
  338.                                  Str255                 userName,
  339.                                  Str255                 password);
  340.  
  341.  
  342. /*---------------------------------------------------------------------------*/
  343. /* AFPChangePassword: Changes the password from oldPassword to newPassword     */
  344. /*---------------------------------------------------------------------------*/
  345.  
  346. EXTERN_API( OSStatus )
  347. AFPChangePassword                (AFPSharedVolumesEnumeratorRef * ref,
  348.                                  StringPtr                 oldPassword,
  349.                                  StringPtr                 newPassword);
  350.  
  351.  
  352.  
  353. #if PRAGMA_STRUCT_ALIGN
  354.     #pragma options align=reset
  355. #elif PRAGMA_STRUCT_PACKPUSH
  356.     #pragma pack(pop)
  357. #elif PRAGMA_STRUCT_PACK
  358.     #pragma pack()
  359. #endif
  360.  
  361. #ifdef PRAGMA_IMPORT_OFF
  362. #pragma import off
  363. #elif PRAGMA_IMPORT
  364. #pragma import reset
  365. #endif
  366.  
  367. #ifdef __cplusplus
  368. }
  369. #endif
  370.  
  371. #endif /* _AFPCLIENT__ */
  372.  
  373.